home *** CD-ROM | disk | FTP | other *** search
/ AGA Toolkit '97 / The AGA Toolkit '97.iso / programming / gui / gadutil / docs / autodocs / 01.gu_layoutgadgetsa < prev    next >
Encoding:
Text File  |  1996-09-07  |  27.2 KB  |  669 lines

  1. gadutil.library/GU_LayoutGadgetsA              gadutil.library/LayoutGadgetsA
  2.  
  3.    NAME
  4.     GU_LayoutGadgetsA -- Formats an array of GadTools gadgets.
  5.  
  6.    SYNOPSIS
  7.     gad_info = GU_LayoutGadgetsA(gad_list, gadgets, screen, taglist)
  8.     D0,A0                        A0        A1       A2      A3
  9.  
  10.     APTR GU_LayoutGadgetsA(struct Gadget **, struct LayoutGadget *,
  11.         struct Screen *, struct TagItem *);
  12.  
  13.    FUNCTION
  14.     Creates a laid-out gadget list from a LayoutGadget array, which
  15.     describes each gadget you want to create. Gadgets you create can
  16.     be any of the gadget kinds supported by GadTools, as well as any
  17.     of the extended gadget kinds provided by GadUtil.
  18.     The gadgets created by this routine, can easily be defined so that
  19.     they adjust their sizes and positions to accomodate fonts of any
  20.     size, and also adapt to different locale strings.
  21.     
  22.    INPUTS
  23.     gad_list - a pointer to the gadget list pointer. This will be
  24.            ready to pass to OpenWindowTagList() or AddGList().
  25.  
  26.     gadgets - an array of LayoutGadget structures. Each element in
  27.           the array describes one of the gadgets that you will
  28.           be creating. Each LayoutGadget structure in the array
  29.           should be initialized as follows:
  30.  
  31.           lg_GadgetID - the ID for this gadget. An ID of -1
  32.                 terminates the array.
  33.  
  34.           lg_LayoutTags - tags that describes each gadget to
  35.                   create. These tags is used to calculate
  36.                   positions, sizes and other attributes
  37.                   of the created gadgets.
  38.  
  39.           lg_GadToolsTags - additional tags for GadTools gadgets.
  40.                     This would be the same set of tags that
  41.                     you might pass to CreateGadgetA() if
  42.                     you were using GadTools directly.
  43.  
  44.           lg_Gadget - the pointer to the Gadget structure created
  45.                   for this gadget will be placed here. You
  46.                   should initialize this field to NULL. The
  47.                   gadget structure created should be considered
  48.                   READ ONLY! This field will contain a pointer
  49.                   to a struct BBoxData, if the created gadget
  50.                   kind is a BEVELBOX_KIND.
  51.  
  52.           Assembly language programmers can use the macro GADGET:
  53.  
  54.             GADGET GadgetID, Gad_LayoutTags, Gad_GadToolsTags
  55.  
  56.     screen - a pointer to the screen that the gadgets will be created
  57.          for. This is required, so that the layuot routines can
  58.          get display info about the screen where the rendering
  59.          will be done. Use LockPubScreen() to use a public screen,
  60.          or OpenScreenTagList(), if you want to use your own screen.
  61.  
  62.     taglist - pointer to an array of tags providing optional extra
  63.           parameters, or NULL.
  64.  
  65.                   These tags can be used here:
  66.  
  67.                     GU_RightExtreme (ULONG *)
  68.                       A pointer to a longword that is used to store the
  69.                       rightmost point that a gadget will exist in.
  70.  
  71.                     GU_LowerExtreme (ULONG *)
  72.                       A pointer to a longword that is used to store the
  73.                       lowermost point that a gadget woll exist in.
  74.  
  75.                     GU_Catalog (struct Catalog *)
  76.                       A pointer to the programs translation catalog. NULL
  77.                       indicates that the program should use the internal
  78.                       strings. You must open the catalog by yourself (use
  79.                       GU_OpenCatalog() or locale/OpenCatalog). The
  80.                       GU_AppStrings tag MUST be used together with this tag.
  81.  
  82.                     GU_DefTextAttr (struct TextAttr *)
  83.                       Specifies the default font to use with all gadgets. Can
  84.                       be overridden with GU_TextAttr tag for each gadget.
  85.  
  86.                     GU_AppStrings (struct AppString *)
  87.                       A pointer to an array of AppString structures. These
  88.                       strutures contains the programs internal strings. This
  89.                       tag must be used together with the GU_Catalog tag.
  90.  
  91.                     GU_BorderLeft (ULONG)
  92.                       Size of the window's left border.
  93.  
  94.                     GU_BorderTop (ULONG)
  95.                       Size of the window's top border.
  96.  
  97.                     GU_NoCreate (BOOL)
  98.                       Don't create any gadgets. Useful to determine if the
  99.                       window will fit on the screen etc.
  100.  
  101.                     GU_MinimumIDCMP (ULONG *)
  102.                       A pointer to a longword that is used to store the
  103.                       minimum required IDCMP flags, so that all gadgets will
  104.                       work. The longword can already be initialized, and any
  105.                       new needed IDCMP flags will be appended to that
  106.                       longword.
  107.  
  108.    TAGS
  109.  
  110.    Tags for the gadgets lg_LayoutTags taglist. The other tags can be found in
  111.    the autodoc to gadtools.library/CreateGadgetA().
  112.  
  113.    GU_GadgetKind (ULONG)
  114.       Can be any of the standard GadTools gadget kinds, or one of the
  115.       extensions provided by GadUtil. Currently extended types are:
  116.  
  117.          IMAGE_KIND
  118.            A gadget that uses an Intuition Image structure for its
  119.            contents. Selected and unselected states can use different
  120.            images. The images are centered automatically.
  121.  
  122.            Extra tags for IMAGE_KIND:
  123.  
  124.               GUIM_Image (struct Image *)
  125.                  Image for the gadget in its unselected state. This is
  126.                  the only required (extra) tag for IMAGE_KIND gadgets.
  127.  
  128.               GUIM_SelectImg (struct Image *)
  129.                  Image for the gadget in its selected state. If this tag
  130.                  is omitted, the selected image will be the same as the
  131.                  unselected, and only the border and the background color
  132.                  will change (depending on the GUIM_BOOPSILook tag).
  133.  
  134.               GUIM_ReadOnly (BOOL)
  135.                  TRUE to create a read-only image gadget.
  136.  
  137.               GUIM_BOOPSILook (BOOL)
  138.                  This tag will allow the programmer to select how the
  139.                  secondary image should be shown, if only one image is
  140.                  used for the gadget. Defaults to TRUE, which means that
  141.                  the background color will change when the user selects
  142.                  the gadget.
  143.  
  144.          DRAWER_KIND
  145.            A "select drawer" image button. This can be used to select
  146.            a path, but is often used to select files.
  147.  
  148.          FILE_KIND
  149.            A "select file" image button. This can be used to allow the
  150.            user to select a file. Most programs uses the DRAWER_KIND
  151.            for both file and path selection.
  152.  
  153.          BEVELBOX_KIND
  154.            A GadTools bevelbox. Use this to avoid the use of absolute
  155.            sizing of bevelboxes. All bevel box kinds from OS3.0 is
  156.            supported, even if the computer only has OS2.0.
  157.  
  158.            Extra tags for BEVELBOX_KIND:
  159.  
  160.               GUBB_Recessed (BOOL)
  161.                  Create a recessed ("pushed in") bevel box. Differs from
  162.                  the GadTools tag GTBB_Recessed, in that it works with
  163.                  both TRUE and FALSE as parameter. GadTools creates a
  164.                  recessed box independent from the given value.
  165.  
  166.                  Defaults to FALSE.
  167.  
  168.               GUBB_FrameType (ULONG)
  169.                  Determines what kind of box this function renders. The
  170.                  current available alternatives are:
  171.  
  172.                     BFT_BUTTON - Generates a box like what is used around
  173.                                  a GadTools BUTTON_KIND gadget.
  174.  
  175.                     BFT_RIDGE - Generates a box like what is used around
  176.                                 a GadTools STRING_KIND gadget.
  177.  
  178.                     BFT_DROPBOX - Generates a box suitable for a standard
  179.                                   icon drop box imagery.
  180.  
  181.                     BFT_HORIZBAR - Generates a horizontal shadowed line.
  182.                                    Can also be used to draw a normal line,
  183.                                    using 1 for the line's height.
  184.  
  185.                     BFT_VERTBAR - Generates a vertical shadowed line. Can
  186.                                   also be used to draw a normal line, using
  187.                                   1 for the line's width.
  188.  
  189.                  Defaults to BFT_BUTTON.
  190.  
  191.               GUBB_TextColor (ULONG)
  192.                  Selects which color to print the title text in. Only useful
  193.                  for a bevelbox with a title. Defaults to the color of the
  194.                  TEXTPEN.
  195.  
  196.              GUBB_TextPen (ULONG)
  197.                  Selects which pen to print the title text in. Only
  198.                  useful for a bevelbox with a title. Defaults to TEXTPEN.
  199.                  This tag overrides the GUBB_TextColor tag.
  200.  
  201.               GUBB_Flags (ULONG)
  202.                  Currently, only text placement flags are defined. These are:
  203.  
  204.                  Y-pos flags
  205.                  ~~~~~~~~~~~
  206.                     BB_TEXT_ABOVE - Places the bevel box text above the upper
  207.                                     border of the box           ___Example___
  208.  
  209.                     BB_TEXT_IN    - Places the bevel box text at the upper
  210.                                     border of the box           ---Example---
  211.  
  212.                     BB_TEXT_BELOW - Places the bevel box text below the upper
  213.                                     border of the box           ___       ___
  214.                                                                    Example
  215.                  X-pos flags
  216.                  ~~~~~~~~~~~
  217.                     BB_TEXT_CENTER - Places the bevel box text in the middle
  218.                                      of the upper border        ---Example---
  219.  
  220.                     BB_TEXT_LEFT   - Places the bevel box text 8 pixels from
  221.                                      the left edge of the box   -Example-----
  222.  
  223.                     BB_TEXT_RIGHT  - Places the bevel box text 8 pixels from
  224.                                      the right edge of the box  -----Example-
  225.  
  226.                  Combined flags
  227.                  ~~~~~~~~~~~~~~
  228.                     BB_TEXT_ABOVE_CENTER - BB_TEXT_ABOVE + BB_TEXT_CENTER
  229.                     BB_TEXT_ABOVE_LEFT   - BB_TEXT_ABOVE + BB_TEXT_LEFT
  230.                     BB_TEXT_ABOVE_RIGHT  - BB_TEXT_ABOVE + BB_TEXT_RIGHT
  231.  
  232.                     BB_TEXT_IN_CENTER    - BB_TEXT_IN + BB_TEXT_CENTER
  233.                     BB_TEXT_IN_LEFT      - BB_TEXT_IN + BB_TEXT_LEFT
  234.                     BB_TEXT_IN_RIGHT     - BB_TEXT_IN + BB_TEXT_RIGHT
  235.  
  236.                     BB_TEXT_BELOW_CENTER - BB_TEXT_BELOW + BB_TEXT_CENTER
  237.                     BB_TEXT_BELOW_LEFT   - BB_TEXT_BELOW + BB_TEXT_LEFT
  238.                     BB_TEXT_BELOW_RIGHT  - BB_TEXT_BELOW + BB_TEXT_RIGHT
  239.  
  240.                  Default if BB_TEXT_ABOVE|BB_TEXT_CENTER. Combine the x and y
  241.                  position flags by OR:ing them together. Don't combine two X
  242.                  or two Y flags together.
  243.                 
  244.                  Shadow placement flags
  245.                  ~~~~~~~~~~~~~~~~~~~~~~
  246.                     BB_SHADOW_DR - Places the bevel box text shadow one pixel
  247.                                    below and to the right of the text. 
  248.  
  249.                     BB_SHADOW_UR - Places the bevel box text shadow one pixel
  250.                                    above and to the right of the text. 
  251.  
  252.                     BB_SHADOW_DL - Places the bevel box text shadow one pixel
  253.                                    below and to the left of the text. 
  254.  
  255.                     BB_SHADOW_UL - Places the bevel box text shadow one pixel
  256.                                    above and to the left of the text. 
  257.  
  258.                     BB_SUNAT_UL  - Another name for BB_SHADOW_DR
  259.                     BB_SUNAT_DL  - Another name for BB_SHADOW_UR
  260.                     BB_SUNAT_UR  - Another name for BB_SHADOW_DL
  261.                     BB_SUNAT_DR  - Another name for BB_SHADOW_UL
  262.  
  263.                  Default if BB_SHADOW_DR (BB_SUNAT_UL).
  264.  
  265.               GUBB_3DText (BOOL)
  266.                  Enables the shadow on the bevel box text. This tag must be
  267.                  used if GUBB_ShadowColor or GUBB_ShadowPen isn't used.
  268.  
  269.              GUBB_ShadowColor (ULONG)
  270.                  Selects which color to print the shadow text in. Only useful
  271.                  for a bevelbox with a title. Defaults to the color of the
  272.                  SHADOWPEN.
  273.  
  274.               GUBB_ShadowPen (ULONG)
  275.                  Selects which pen to print the shadow text in. Only useful
  276.                  for a bevelbox with a title. Defaults to SHADOWPEN.
  277.                  This tag overrides the GUBB_ShadowColor tag.
  278.  
  279.          PROGRESS_KIND
  280.            Gadget used to display a value out of a total. Can be used to
  281.            display the progress of a search, a diskcopy or anything else.
  282.  
  283.            Extra tags for PROGRESS_KIND:
  284.  
  285.               GUPR_FillColor (ULONG)
  286.                  Selects which color to use to paint the current value of
  287.                  the progress requester with. Defaults to the color of the
  288.                  FILLPEN.
  289.  
  290.               GUPR_FillPen (ULONG)
  291.                  Selects which pen to use to paint the current value of
  292.                  the progress requester with. Defaults to the FILLPEN.
  293.                  This tag overrides the GUPR_FillColor tag.
  294.  
  295.               GUPR_BackColor (ULONG)
  296.                  Selects which color to fill the background of the progress
  297.                  requester with. Defaults to the color of the BACKGROUNDPEN.
  298.  
  299.               GUPR_BackPen (ULONG)
  300.                  Selects which pen to fill the background of the progress
  301.                  requester with. Defaults to the BACKGROUNDPEN.
  302.                  This tag overrides the GUPR_BackColor tag.
  303.  
  304.               GUPR_Current (ULONG)
  305.                  The initial current value of the progress requester. The
  306.                  gadget's current value may be changed later by directly
  307.                  modifying the pg_Current field of the ProgressGad structure.
  308.                  Use GU_UpdateProgress to redraw the progress requester with
  309.                  the new value. The pg_Current field must not be larger than
  310.                  4.294.967.295 / the width of the progress gadget. A "normal"
  311.                  width of 410 pixels allows a current value of 10.737.418.
  312.          Defaults to 0.
  313.  
  314.               GUPR_Total (ULONG)
  315.                  The initial total value of the progress requester. The
  316.                  gadget's total value may be changed later by directly
  317.                  modifying the pg_Total field of the ProgressGad structure.
  318.                  Use GU_UpdateProgress to redraw the progress requester with
  319.                  the new value. The total value can be as large as a longword
  320.                  allows (4.294.967.295), but you can't display a current value
  321.                  larger than 4.294.967.295 / the width of the progress gadget.
  322.          Defaults to 100.
  323.  
  324.          Changed tags, and additions to GadTools:
  325.  
  326.          LISTVIEW_KIND
  327.  
  328.            GTLV_ShowSelected (UWORD id)
  329.  
  330.               This tag was changed, so that you don't have to create the
  331.               string gadget before all other gadgets. The difference from
  332.               this tag in GadTools, is that we now have to give the ID of
  333.               the string gadget to use to show the selected item.
  334.  
  335.               An example of a valid (and probably most useful) gadget to
  336.               use for GTLV_ShowSelected:
  337.  
  338.               ShowSelGad:
  339.                   dc.l    GU_GadgetKind,  STRING_KIND,    GU_AutoHeight,  4
  340.                   dc.l    GU_DupeWidth,   GAD_LISTVIEW,   GU_GadgetText,  NULL
  341.                   dc.l    TAG_DONE
  342.  
  343.               This gadget MUST be before the LISTVIEW gadget in the LayoutGadget
  344.               array.
  345.  
  346.               Special:
  347.  
  348.               ti_Data = -1    Creates a read-only gadget below the listview,
  349.                               same as for GTLV_ShowSelected, 0  for GadTools.
  350.  
  351.               ti_Data =  x    Gadget ID for the gadget that the selected item
  352.                               should be displayed in. Same as GadTools reaction
  353.                               on a gadget pointer in ti_Data.
  354.  
  355.               This gadget's ti_Data field will be changed during the creation
  356.               of the gadget, but will be changed back before GU_LayoutGadgets
  357.               returns.
  358.  
  359.          MX_KIND
  360.           The gng_GadgetText field in the NewGadget structure can be used
  361.           even with MX_KIND gadgets. This should have been included in
  362.           GadTools. The gadget text will always be placed ABOVE the gadget,
  363.           on the same side as the other texts for the gadget. Positions are
  364.           checked against WBPattern & SerialPrefs to get them "right". The
  365.           GU_GadgetText and GU_LocaleText tags are used to access this field.
  366.  
  367.  
  368.    Tags for all gadget kinds:
  369.  
  370.    Gadget width control:
  371.  
  372.       GU_Width (UWORD wid)
  373.          Absolute width of the gadget. Not recommended to use for other
  374.          gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  375.  
  376.       GU_DupeWidth (UWORD id)
  377.          Duplicate the width of another gadget.
  378.  
  379.       GU_AutoWidth (WORD add)
  380.          Width = length of text label + ti_Data. For CYCLE_KIND gadgets,
  381.      the gadget width will be calculated by checking the length of
  382.      all alternatives and using the one that is widest + 26 as width.
  383.  
  384.       GU_Columns (UWORD numcols)
  385.          Set the gadget width so that approximately ti_Data columns of
  386.          text will fit.
  387.  
  388.       GU_AddWidth (WORD add)
  389.          Add ti_Data to the total width calculation.
  390.  
  391.       GU_MinWidth (UWORD wid)
  392.          Make the gadget at least ti_Data pixels wide.
  393.  
  394.       GU_MaxWidth (UWORD wid)
  395.          Make the gadget at most ti_Data pixels wide.
  396.  
  397.       GU_AddWidChar (WORD chars)
  398.          Add the length of ti_Data characters to the total width calculation.
  399.  
  400.       GU_FractWidth (LONG parts)
  401.      Divide or multiply the gadget's width with ti_Data. A positive
  402.      value divides the gadget's width by the ti_Data, a negative ti_Data
  403.      multiplies the gadget's width with ti_Data.
  404.  
  405.     Gadget height control:
  406.  
  407.       GU_Height (UWORD hei)
  408.          Absolute height of the gadget. Not recommended to use for other
  409.          gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  410.         
  411.       GU_DupeHeight (UWORD id)
  412.          Duplicate the height of another gadget.
  413.  
  414.       GU_AutoHeight (WORD add)
  415.          Height = height of the gadget's font + ti_Data. This tag doesn't
  416.          work as it should with MX_KIND gadgets. Will be fixed later.
  417.          Use GU_HeightFactor or GU_Height for MX_KIND until this is fixed.
  418.  
  419.       GU_HeightFactor (UWORD numlines)
  420.          Set the gadget height to approximately ti_Data lines.
  421.  
  422.       GU_AddHeight (WORD add)
  423.          Add ti_Data to the total height calculation.
  424.  
  425.       GU_MinHeight (UWORD wid)
  426.          Make the gadget at least ti_Data pixels high.
  427.  
  428.       GU_MaxHeight (UWORD wid)
  429.          Make the gadget at most ti_Data pixels high.
  430.  
  431.       GU_AddHeiLines (WORD numlines)
  432.          Add the height of ti_Data/2 lines to the final height calculation.
  433.          The numlines argument is given in units of 1/2 lines to get
  434.          better resolution (ti_Data of 4 means that the height of 2
  435.          lines should be added).
  436.  
  437.       GU_FractHeight (LONG parts)
  438.      Divide or multiply the gadget's height with ti_Data. A positive
  439.      value divides the gadget's height by the ti_Data, a negative ti_Data
  440.      multiplies the gadget's height with ti_Data.
  441.  
  442.    Gadget top edge control:
  443.  
  444.       GU_Top, GU_TopRel and GU_AlignTop locks the top edge of the gadget, and
  445.       allows any bottom edge control tag to adjust the height, so that both
  446.       top and bottom edges will be correct.
  447.  
  448.       GU_Top (UWORD ypos)
  449.          Absolute top edge of the gadget. Not recommended to use for other
  450.          gadgets than the top-most gadgets.
  451.  
  452.       GU_TopRel (UWORD id)
  453.          Make the top edge relative to another gadgets bottom edge. This
  454.          gadget will be placed BELOW the given gadget.
  455.  
  456.       GU_AddTop (WORD add)
  457.          Add ti_Data to the final top edge calculation.
  458.  
  459.       GU_AlignTop (UWORD id)
  460.          Align the top edge of the gadget with another gadgets top edge.
  461.  
  462.       GU_AdjustTop (WORD add)
  463.          Add the height of the text font + ti_Data to the top edge.
  464.  
  465.       GU_AddTopLines (WORD numlines)
  466.          Add the height of ti_Data/2 lines to the final top edge. The
  467.          numlines argument is given in units of 1/2 lines to get better
  468.          resolution (ti_Data of 4 means that the height of 2 lines
  469.          should be added).
  470.  
  471.    Gadget bottom edge control:
  472.  
  473.       GU_Bottom, GU_BottomRel and GU_AlignBottom locks the bottom edge of the
  474.       gadget, and allows any top edge control tag to adjust the height, so that
  475.       both top and bottom edges will be correct.
  476.  
  477.       GU_Bottom (UWORD ypos)
  478.          Absolute bottom edge of the gadget. Not recommended to use for other
  479.          gadgets than the bottom-most gadgets. Should not be necessary to use
  480.          at all.
  481.  
  482.       GU_BottomRel (UWORD id)
  483.          Make the bottom edge relative to another gadgets top edge. This
  484.          gadget will be placed ABOVE the given gadget.
  485.  
  486.       GU_AddBottom (WORD add)
  487.          Add ti_Data to the final bottom edge calculation.
  488.  
  489.       GU_AlignBottom (UWORD id)
  490.          Align the bottom edge of the gadget with another gadgets bottom edge.
  491.  
  492.       GU_AdjustBottom (WORD add)
  493.          Subtract the height of the gadget's font + ti_Data from the top edge.
  494.          This will move the gadget UPWARDS (ti_Data + font height) pixels.
  495.  
  496.    Gadget left edge control:
  497.  
  498.       GU_Left, GU_LeftRel and GU_AlignLeft locks the left edge of the gadget,
  499.       and allows any right edge control tag to adjust the width, so that both
  500.       left and right edges will be correct.
  501.  
  502.       GU_Left (UWORD xpos)
  503.          Absoulute left edge of the gadget. Not recommended to use for other
  504.          gadgets than the left-most gadgets.
  505.  
  506.       GU_LeftRel (UWORD id)
  507.          Make the left edge relative to another gadgets right edge. This
  508.          gadget will be placed TO THE RIGHT of the given gadget.
  509.  
  510.       GU_AddLeft (WORD add)
  511.          Add ti_Data to the final left edge calculation.
  512.  
  513.       GU_AlignLeft (UWORD id)
  514.          Align the left edge of the gadget with another gadgets left edge.
  515.  
  516.       GU_AdjustLeft (WORD add)
  517.          Add the width of the gadget label + ti_Data to the left edge.
  518.  
  519.       GU_AddLeftChar (WORD chars)
  520.          Add the length of ti_Data characters to the left edge.
  521.  
  522.    Gadget right edge control:
  523.  
  524.       GU_Right, GU_RightRel and GU_AlignRight locks the right edge of the
  525.       gadget, and allows any left edge control tag to adjust the width, so
  526.       that both left and right edges will be correct.
  527.  
  528.       GU_Right (UWORD xpos)
  529.          Absoulute right edge of the gadget. Not recommended to use for other
  530.          gadgets than the right-most gadgets. Should not be necessary to use
  531.          at all.
  532.  
  533.       GU_RightRel (UWORD id)
  534.          Make the right edge relative to another gadgets left edge. This
  535.          gadget will be placed TO THE LEFT of the given gadget.
  536.  
  537.       GU_AddRight (WORD add)
  538.          Add ti_Data to the final right edge calculation.
  539.  
  540.       GU_AlignRight (UWORD id)
  541.          Align the right edge of the gadget with another gadgets right edge.
  542.  
  543.       GU_AdjustRight (WORD add)
  544.          Add the width of the gadget label + ti_Data to the left edge.
  545.  
  546.     Other tags:
  547.  
  548.       GU_ToggleSelect (BOOL)
  549.          Create a toggle select gadget. Works with BUTTON_KIND and IMAGE_KIND
  550.          gadgets.
  551.  
  552.       GU_Selected (BOOL)
  553.          Set the initial value of a toggle select gadget.
  554.  
  555.       GU_Hotkey (CHAR)
  556.          Hotkey that should simulate a press (release) of a gadget.
  557.  
  558.       GU_HotkeyCase (BOOL)
  559.          Make the hotkey case-sensitive. Default is not case sensitive.
  560.  
  561.       GU_LabelHotkey (BOOL)
  562.          Get the hotkey directly from the gadget's label. The hotkey can
  563.          be case-sensitive, but not for CYCLE, LISTVIEW and MX gadgets.
  564.  
  565.       GU_RawKey (BYTE)
  566.          Use a rawkey as a gadget hotkey. May not be case-sensitive.
  567.         
  568.    Tags that gives access to other fields in the NewGadget structure:
  569.  
  570.       GU_GadgetText (UBYTE *)
  571.          A pointer to the gadget's label. Will be copied directly into the
  572.          gng_GadgetText field of the NewGadget structure.
  573.  
  574.       GU_TextAttr (struct TextAttr *)
  575.          A pointer to an initialized TextAttr structure (to select the font).
  576.          Will be copied directly into the gng_TextAttr field of the NewGadget
  577.          structure.
  578.  
  579.       GU_Flags (ULONG)
  580.          Gadget flags. Currently available flags are as for GadTools, but
  581.          here is a short list of them:
  582.  
  583.          PLACETEXT_LEFT - Place the gadget label right aligned on the left
  584.                           side of the gadget.
  585.  
  586.          PLACETEXT_RIGHT - Place the gadget label left aligned on the right
  587.                            side of the gadget.
  588.  
  589.          PLACETEXT_ABOVE - Place the gadget label centered above the gadget.
  590.  
  591.          PLACETEXT_BELOW - Place the gadget label centered below the gadget.
  592.  
  593.          PLACETEXT_IN - Place the gadget label centered inside the gadget.
  594.  
  595.          NG_HIGHLABEL - Highlight the label (render it using SHINEPEN).
  596.  
  597.       GU_UserData (APTR)
  598.          Storage for your own data. Will probably be removed, since GadUtil
  599.          uses this filed for an internal structure (with some external
  600.          available fields).
  601.  
  602.       GU_LocaleText (ULONG stringid)
  603.          Get gadget label from a catalog. This allows easy localization of
  604.          all new programs.
  605.  
  606.  
  607.    RESULT
  608.     gad_info - a pointer to a private structure. You must keep this
  609.            value and pass it to GU_FreeLayoutGadgets() later on
  610.            in order to free up all resources used by your gadgets.
  611.            This pointer is also used in a lot of other functions
  612.            in this library.
  613.  
  614.    NOTES
  615.     You must be careful with the taglist in the lg_LayoutTags field.
  616.     Tags are processed sequentally in the order you give them in, and
  617.     if a tag references another gadget (eg. the GL_TopRel tag), then
  618.     processing of the current gadget halts while the referenced gadget
  619.     is processed (if it has not already been processed). Problems can
  620.     occur if this gadget refers back to the original gadget that
  621.     referenced if, if it is referring to a field that has not yet been
  622.     processed in that gadget.
  623.  
  624.         Also note that you do not have to specify any tags that do not
  625.         change from gadget to gadget. Just be sure that you know in which
  626.     order the gadgets are processed (eg. relatives etc).
  627.  
  628.     Another thing to note, is that we have tried to make the processing
  629.     of position and width / height tags as usable as possible, what I
  630.     mean with this, is that if you eg first define the left edge and
  631.     then define the right edge, the width will change. BUT, there are
  632.     special cases when this isn't true. This is because we have tried
  633.     out this and decided that this was the best way to do it.
  634.  
  635.     Here comes some examples of the special cases;
  636.  
  637.     dc.l    GU_AlignLeft, GAD_1    ; Left edge aligned with GAD_1's left.
  638.     dc.l    GU_AlignRight, GAD_2    ; This stretches the gadget, so that
  639.                     ; both the left and right edges are
  640.                     ; positioned as defined.
  641.     ; Then, if we want to move the right edge 2 pixels right, and the left
  642.     ; edge two pixels right, we might try this:
  643.  
  644.     dc.l    GU_AddLeft, -2        ; This works as we want, it moves the
  645.                     ; left edge to the right place, but it
  646.                     ; also moves the whole gadget two
  647.                     ; pixels left..
  648.  
  649.     dc.l    GU_AddRight, 2        ; <- This is a common mistake. This
  650.                     ; moves the whole gadget to the right.
  651.                     ; Ie. it is moved back to the old
  652.                     ; position, not as we wanted...
  653.  
  654.     ; But if we replace the previous line with the following;
  655.  
  656.     dc.l    GU_AddWith,4        ; This works just as we wanted it to.
  657.                     ; Now the gadget should be 4 pixels
  658.                     ; wider, two to the left and two to
  659.                     ; the right.
  660.  
  661.     The same goes for GU_AddHeight and GU_AddBottom etc.
  662.  
  663.     This is actually a feature. Sometimes you might want to move the whole
  664.     button, so we made it work this way.
  665.  
  666.  
  667.    SEE ALSO
  668.     GU_FreeLayoutGadgets(), GU_CreateGadgetA(), gadtools/CreateGadgetA()
  669.